package timbap.visualizer.api.plugin.poscloud;

import timbap.visualizer.api.model.PlaylistEntry;
import timbap.visualizer.api.plugin.Plugin;

import java.util.Collection;
import java.util.Comparator;
import java.util.Map;

/**
 * The <code>PosCloudPlugin</code> is a special kind of timbap plugin
 * that is used to present an index of the playlist in the so called
 * positioning cloud.
 *
 * The index consists of positioning cloud elements. The implementation
 * of a <code>PosCloudPlugin</code> has to provide methods to create,
 * sort, find and draw the respective elements of an arbitrary type.
 *
 * Additionally, a comparator of playlist entries has to be provided
 * in order to assure that the playlist can be sorted according to the index.
 *
 * @author  Andreas Pabst
 * @see     timbap.visualizer.api.plugin.Plugin
 */
public interface PosCloudPlugin<E> extends Plugin {
    
    /**
     * sorts the positioning cloud elements
     * 
     */
    public void sortPosCloudElements();
    
    /**
     * finds the positioning cloud element that is associated 
     * with a given playlist entry
     * 
     * @param pPlaylistEntry	the playlist entry
     * @return	the positioning cloud element associated with the playlist entry
     */
    public E findPosCloudElement(PlaylistEntry pPlaylistEntry);
    
    /**
     * creates a positioning cloud element for the given
     * playlist entry.
     * 
     * @param pPlaylistEntry
     * @return
     */
    public E createPosCloudElement(PlaylistEntry pPlaylistEntry);
    
    /**
     * gets the positioning cloud elements
     * 
     * @return the positioning cloud elements
     */
    public Collection<E> getPosCloudElements();

    /**
     * gets the map of playlist entries and associated 
     * positioning cloud elements
     * 
     * @return the map of playlist entries and associated positioning cloud elements
     */
    public Map<PlaylistEntry, E> getPosCloudElementMap();
    
    /**
     * draws the given positioning cloud element
     * 
     * @param pPosCloudElement	the positioning cloud element to draw 
     * @param pIsSelected		whether the positioning cloud element is currently selected
     */
    public void drawPosCloudElement(E pPosCloudElement, boolean pIsSelected);
    
    /**
     * returns a comparator of playlist entries that should sort the
     * playlist entries according to the order implicitly specified by the
     * positioning cloud element type's implementation of the 
     * <code>Comparable</code> interface.
     * 
     * @return	a comparator of playlist entries compatible with the positioning cloud element sorting
     */
    public Comparator<PlaylistEntry> getPlaylistEntryComparator();
    //TODO This should better be replaced by using a sorted map
}
